AI Service > AI Fashion > Service APIガイド

  • AI Fashion検索サービスを使用するために必要なAPIを説明します。

API共通情報

事前準備

  • APIを使用するにはプロジェクト統合AppkeyまたはサービスAppkeyが必要です。
    • プロジェクト統合Appkeyを使用することを推奨します。
    • プロジェクト統合Appkeyはプロジェクト設定ページのAPIセキュリティ設定で作成して使用できます。
    • サービスAppkeyはコンソール上部のURL & Appkeyメニューで確認が可能です。

リクエスト共通情報

  • APIを使用するにはセキュリティキー認証処理が必要です。

[APIドメイン]

リージョン ドメイン
韓国(パンギョ) https://kr1-aifashion.api.nhncloudservice.com
韓国(ピョンチョン) https://kr2-aifashion.api.nhncloudservice.com
韓国(クァンジュ) https://kr3-aifashion.api.nhncloudservice.com
日本(東京) https://jp1-aifashion.api.nhncloudservice.com
米国(カリフォルニア) https://us1-api-aifashion.nhncloudservice.com

入力画像ガイド

  • 入力画像のダウンロードに3秒以上かかる場合は失敗とみなします。
  • 入力イ画像ファッションアイテムの幅と高さがどちらも20px以下の場合は認識しません。
  • 画像サイズの大きさに比例してファッションアイテムのサイズも大きくすると正確に認識できます。
  • 画像内でファッションアイテムが占める割合が大きいほど正確に認識できます。
  • 画像ファイルの最大サイズ:5,000,000 bytes(ただし、tag APIは1,000,000 bytes)
  • サポート画像フォーマット:PNG、JPEG、GIF
  • イメージURLにポートを直接指定する場合は80、443、10000~12000ポートのみ使用できます。

フィルタリングガイド

  • フィルタリング機能は、カテゴリまたはフィルターを制限して検索するときに使用します。

対象フィールド

名前 フィールド名
カテゴリー1depth category1_id
カテゴリー2depth category2_id
カテゴリー3depth category3_id
フィルター1 s1
フィルター2 s2

文法

  • filter.{フィールド名}=演算子:
条件 演算子 説明
equal(default) equal filter.category2_id=1003,1005 or
filter.category2_id=equal:1003 or
filter.category2_id=equal:1003&filter.s1=equal:1
対象フィールドの値がパラメータ値と同じ文書のみ結果としてレスポンスします。
コンマ(,)で区切ってOR検索が可能です。
not equal !equal filter.category2_id=!equal:1003 or
filter.category2_id=!equal:1003,1005 or
filter.category2_id=!equal:1003,1005&filter.s1=!equal:1
対象フィールドの値がパラメータ値と異なる文書のみ結果としてレスポンスします。
コンマ(,)で区切ってOR検索が可能です。

レスポンス共通情報

  • すべてのAPIリクエストに「200 OK」でレスポンスします。詳細なレスポンス結果はレスポンス本文ヘッダを参照します。

[レスポンス本文ヘッダ]

名前 タイプ 説明
header.isSuccessful boolean true:正常
false:エラー
header.resultCode int 0:正常
0より大きい:部分成功
負の数:エラー
header.resultMessage string "SUCCESS":正常
その他:エラーメッセージを返す

[成功レスポンス本文例]

{
        "header": {
                "isSuccessful": true,
                "resultCode": 0,
                "resultMessage": "SUCCESS"
        }
}

[失敗レスポンス本文例]

{
        "header": {
                "isSuccessful": false,
                "resultCode": -40000,
                "resultMessage": "InvalidParam"
        }
}

サービス監理

サービスID登録

  • サービスIDを登録することができるAPI
  • 最大5個まで登録可能
  • 許可文字
    • 英字小文字、数字、(-)、(_)許可
    • 2~32文字まで許可
    • 最初の文字は英字小文字のみ許可

リクエスト

[URI]

メソッド URI
POST /nhn-ai-fashion/v1.0/appkeys/{appKey}/service/{serviceID}

[Path Variable]

名前 説明
appKey 統合AppkeyまたはサービスAppkey
serviceID サービスID
リクエスト例
curl -X POST "${domain}/nhn-ai-fashion/v1.0/appkeys/{appKey}/service/{serviceID}"

レスポンス

レスポンス本文例
{
    "header": {
        "isSuccessful": true,
        "resultCode": 0,
        "resultMessage": "SUCCESS"
    }
}

エラーコード

resultCode resultMessage 説明
-40000 InvalidParam パラメータにエラーがある
-41000 UnauthorizedAppKey 承認されていないAppkey
-42010 DuplicateServiceID 重複するサービスID
-42030 ServiceIDQuotaExceededException 許可されたサービスID数超過
-50000 InternalServerError サーバーエラー

サービスID削除

  • 登録されたサービスIDを削除することができるAPI
  • サービスIDに処理中のインデックスリクエストがある場合は、サービスIDを削除できません。

リクエスト

[URI]

メソッド URI
DELETE /nhn-ai-fashion/v1.0/appkeys/{appKey}/service/{serviceID}

[Path Variable]

名前 説明
appKey 統合AppkeyまたはサービスAppkey
serviceID サービスID
リクエスト例
curl -X DELETE "${domain}/nhn-ai-fashion/v1.0/appkeys/{appKey}/service/{serviceID}"

レスポンス

レスポンス本文例
{
    "header": {
        "isSuccessful": true,
        "resultCode": 0,
        "resultMessage": "SUCCESS"
    }
}

エラーコード

resultCode resultMessage 説明
-40000 InvalidParam パラメータにエラーがある
-41000 UnauthorizedAppKey 承認されていないAppkey
-42000 NotExistServiceID 登録されていないサービスID
-42020 CannotDeletedOnIndexRunning インデックス中は削除できません。
-50000 InternalServerError サーバーエラー

サービスIDリスト

  • 登録されたサービスIDリストを確認することができるAPI

リクエスト

[URI]

メソッド URI
GET /nhn-ai-fashion/v1.0/appkeys/{appKey}/services

[Path Variable]

名前 説明
appKey 統合AppkeyまたはサービスAppkey
リクエスト例
curl -X GET "${domain}/nhn-ai-fashion/v1.0/appkeys/{appKey}/services"

レスポンス

[レスポンス本文データ]

名前 タイプ 必須 説明
data.totalCount Number O 5 検索結果の総数
data.items[].serviceID String O my-service サービスID
レスポンス本文例
{
    "header": {
        "isSuccessful": true,
        "resultCode": 0,
        "resultMessage": "SUCCESS"
    },
    "data": {
        "totalCount": 2,
        "items": [{
                "serviceID": "my-service"
            },
            {
                "serviceID": "second_service"
            }
        ]
    }
}

エラーコード

resultCode resultMessage 説明
-40000 InvalidParam パラメータにエラーがある
-41000 UnauthorizedAppKey 承認されていないAppkey
-50000 InternalServerError サーバーエラー

類似画像商品推薦

Search By ProductID

  • 商品IDを基に類似したファッションアイテムを含む商品を探すAPI

リクエスト

[URI]

メソッド URI
GET /nhn-ai-fashion/v1.0/appkeys/{appKey}/service/{serviceID}/product/{productID}

[Path Variable]

名前 説明
appKey 統合AppkeyまたはサービスAppkey
serviceID サービスID
productID 商品ID

[URL Parameter]

名前 タイプ 必須 説明
limit int O 100 最大サイズ
1以上200以下で設定可能
filter.category1_id string X equal:3 category1_id値でフィルタリング
filter.category2_id string X !equal:3 category2_id値でフィルタリング
filter.category3_id string X !equal:3 category3_id値でフィルタリング
filter.s1 string X equal:3 s1値でフィルタリング
filter.s2 string X !equal:3 s2値でフィルタリング
threshold float32 X 0.8 マッチングしたかどうかを判断する類似度基準値
data.items[].similarity >= thresholdの項目のみマッチングしたと判断します。
0超過1.0以下に設定可能
リクエスト例
curl -X GET "${domain}/nhn-ai-fashion/v1.0/appkeys/{appKey}/service/{serviceID}/product/{productID}?limit=100&filter.s1=equal:1"

レスポンス

[レスポンス本文データ]

名前 タイプ 必須 説明
data.totalCount Number O 100 検索結果の総数
data.query String O productID=10234455&limit=100 検索クエリ
data.items[].similarity Number O 0.91234 検索類似度スコア
data.items[].productID String O 8980335 商品ID
レスポンス本文例
{
    "header": {
        "isSuccessful": true,
        "resultCode": 0,
        "resultMessage": "SUCCESS"
    },
    "data": {
        "totalCount": 100,
        "query": "productID=10234455&limit=100",
        "items": [{
                "similarity": 0.91234,
                "productID": "8980335"
            },
            {
                "similarity": 0.81234,
                "productID": "7980335"
            }
        ]
    }
}

エラーコード

resultCode resultMessage 説明
-40000 InvalidParam パラメータにエラーがある
-40050 NotFoundProductIDError 商品IDがない
-41000 UnauthorizedAppKey 承認されていないAppkey
-42000 NotExistServiceID 登録されていないサービスID
-50000 InternalServerError サーバーエラー

カメラ検索

Detect

  • 入力画像からファッションアイテムを検出するAPIです。

リクエスト

[URI]

メソッド URI
GET /nhn-ai-fashion/v1.0/appkeys/{appKey}/service/{serviceID}/detect

[Path Variable]

名前 説明
appKey 統合AppkeyまたはサービスAppkey
serviceID サービスID

[URL Parameter]

名前 タイプ 必須 説明
path String O https://imagecdn.co.kr/sample_image.jpg URL Encodingされた画像のurl
リクエスト例
curl -X GET "${domain}/nhn-ai-fashion/v1.0/appkeys/{appKey}/service/{serviceID}/detect?path=https%3A%2F%2Fimagecdn.co.kr%2Fsample_image.jpg"

レスポンス

[レスポンス本文データ]

名前 タイプ 必須 説明
data.totalCount Number O 100 検索結果の総数
data.query String O path=https://imagecdn.co.kr/sample_image.jpg 検索クエリ
data.items[].link String O eyJwYXRoIjoHR0cHM6Ly9zMy11cy13ZXN0LTIuW...VlfX0= search by imageで使用するリンク
data.items[].center float64 array O [0.825047801147227, 0.330948979591837] 検出されたアイテムの中央x、y座標%
data.items[].b0 float64 array O [0.676864247418738, 0.219377551020408] 検出されたアイテムのx0、y0座標%
data.items[].b1 float64 array O [0.973231355525813, 0.4426204081632654] 検出されたアイテムのx1、y1座標%
data.items[].score float32 O 0.9732 検出されたアイテムの信頼度
レスポンス本文例
{
    "header": {
        "isSuccessful": true,
        "resultCode": 0,
        "resultMessage": "SUCCESS"
    },
    "data": {
        "totalCount": 2,
        "query": "path=https%3A%2F%2Fimagecdn.co.kr%2Fsample_image.jpg",
        "items": [{
                "link": "eyJwYXRoIjoHR0cHM6Ly9zMy11cy13ZXN0LTIuW1hem9uYXdzLmNvbS9mZy1pbWFnZS1zZWFyY2gvMjAxOTEyMDIvNDIyMDZmWYtYWI0Ni00Zjk2LThkYWItZGRkZjllMTI3VjLm9jdGV0LXN0cmVbsInR5cGUiOiJBTEwiLCJpbnB1dHMiOlt7ImJveCI6eyJsZWZ0IjozNQsInRvcCI6MTcyLCJ3aWR0aCI6MTU1LCJoZWlnaHQiOjE3NX0sInNjb3JlIjowg4NjAyODcwNzAyNzQzNTMsInR5cGUiOiJKQUNLRVfV0sImNvbmZpZ3MiOnsiY2FtZXJjp0cnVlfX0=",
                "center": [0.825047801172275, 0.330998979591837],
                "b0": [0.676864244718738, 0.219387751020408],
                "b1": [0.973231357555813, 0.4426020401632654],
                "score": 0.97323
            },
            {

                "link": "eyJwYXRoIjoiaHR0cHM6Ly9zMy11cy13ZXN0LTIuW1hem9uYXdzLmNvbS9mZy1pbWFnZSZWFyY2gvMjAxOTEyMDIvNDIyMDZmWYtYWI0Ni00Zjk2LThkYWItZGRkZjllMTI3OWVm9jdGV0LXN0cmSIsInR5cGUiOiJBTEwiLpbnB1dHMiOlt7ImJveCI6eyJsZWZ0IjozNQsInRvcCI6MyLCJ3aWR0aCI6MTU1LCJoZWlnaHQiOjE3NX0sInNjb3JlIjowLjg4NjAyODcwNzAyNzQzNTMsInR5cGUiOiJKQUNLRVQifV0sImNvbmZpZiOnsiY2FtZXJhIjp0cnVlfX0=",
                "center": [0.3929254301032506, 0.572066265306123],
                "b0": [0.3288718929253023, 0.506377551204082],
                "b1": [0.456978967952199, 0.637751020408163],
                "score": 0.97123

            }
        ]
    }
}

エラーコード

resultCode resultMessage 説明
-40000 InvalidParam パラメータにエラーがある
-41000 UnauthorizedAppKey 承認されていないAppkey
-42000 NotExistServiceID 登録されていないサービスID
-45020 ImageTooLargeException 画像ファイルが大きすぎる
入力画像ガイド参考
-45040 InvalidImageFormatException サポートしていない画像形式
入力画像ガイド参考
-45050 InvalidImageURLException アクセスできないURL
-45060 ImageTimeoutError 画像ダウンロード時間超過
-50000 InternalServerError サーバーエラー

Search By Image

  • detect apiから返されたlinkを基に類似したファッションアイテムを含む商品を探すAPI

リクエスト

[URI]

メソッド URI
GET /nhn-ai-fashion/v1.0/appkeys/{appKey}/service/{serviceID}/image

[Path Variable]

名前 説明
appKey 統合AppkeyまたはサービスAppkey
serviceID サービスID

[URL Parameter]

名前 タイプ 必須 説明
limit int O 100 最大サイズ
1以上200以下で設定可能
link string O eyJwYXRoIjoHR0cHM6Ly9zMy11cy13ZXN0LTIuW...VlfX0%3D detect APIから伝達されたlink(URL encodingが必要)
filter.category1_id string X equal:3 category1_id値でフィルタリング
filter.category2_id string X !equal:3 category2_id値でフィルタリング
filter.category3_id string X !equal:3 category3_id値でフィルタリング
filter.s1 string X equal:3 s1値でフィルタリング
filter.s2 string X !equal:3 s2値でフィルタリング
threshold float32 X 0.8 マッチングしたかどうかを判断する類似度基準値
data.items[].similarity >= thresholdの項目のみマッチングしたと判断します。
0超過1.0以下に設定可能
リクエスト例
curl -X GET "${domain}/nhn-ai-fashion/v1.0/appkeys/{appKey}/service/{serviceID}/image?limit=100&link=eyJwYXRoIjoiaHR0cHM6Ly9zMy11cy13ZXN0LTIuW1hem9u1XdzLmNvbS9mZy1pbWFnZSZWFyY2gvMjAxOTEyMDIvNDIyMDZmWYtYWI0Ni00Zjk2LThkYWItZGRkZjllMTI3OWVm9jdGV0LXN0cmSIsInR5cGUi0iJBTEwiLpbnB1dHMiOlt7ImJveCI6eyJsZWZ0IjozNQaInRvcCI6MyLCJ3aWR0aCI6MTU1LCJoZWlnaHQiOjE3NX0sInNjb3JlIjowLjg4NjAyODcwNzAyNzQzNTMsInR5cGUiOiJKQUNLRVQifV0sImNvbmZpZiOnsiY2FtZXJhIjp0cnVlfX0%3D&filter.s1=equal:1"

レスポンス

[レスポンス本文データ]

名前 タイプ 必須 説明
data.totalCount Number O 100 検索結果の総数
data.query String O link=eyJwYXRoIjoHR0cHM6Ly9zMy11cy13ZXN0LTIuW...VlfX0=&limit=100 検索クエリ
data.items[].similarity Number O 0.91234 検索類似度スコア
data.items[].productID String O 8980335 商品ID
レスポンス本文例
{
    "header": {
        "isSuccessful": true,
        "resultCode": 0,
        "resultMessage": "SUCCESS"
    },
    "data": {
        "totalCount": 100,
        "query": "link=eyJwYXRoIjoiaHR0cHM6Ly9zMy11cy13ZXN0LTIuW1hem9uYXdzLmNvbS9mZy1pbWfnZSZWFyY2gvMjAxOTEyMDIvNDIyMDZmWYtYWI0Ni00Zjk2LThkYWItZGRkZjllMTI3OWVm9jdGV0LXN0cmSIsInR5cGUiOiJBTEwiLpbnB1dHMi0lt7ImJveCI6eyJsZWZ0IjozNQsInRvcCI6MyLCJ3aWa0aCI6MTU1LCJozWlnaHQiOjE3NX0sInNjb3JlIjowLjg4NjAyODcwNzAyNzQzNTMsInR5cGUiOiJKQUNLRVQifV0sImNvbmZpZiOnsiY2FtZXJhIjp0cnVlfX0=&limit=100",
        "items": [{
                "similarity": 0.91234,
                "productID": "8980335"
            },
            {
                "similarity": 0.81234,
                "productID": "7980335"
            }
        ]
    }
}
レスポンスコード
resultCode resultMessage 説明
-40000 InvalidParam パラメータにエラーがある
-41000 UnauthorizedAppKey 承認されていないAppkey
-42000 NotExistServiceID 登録されていないサービスID
-45020 ImageTooLargeException 画像ファイルが大きすぎる
入力画像ガイド参考
-45040 InvalidImageFormatException サポートしていない画像形式
入力画像ガイド参考
-45050 InvalidImageURLException アクセスできないURL
-45060 ImageTimeoutError 画像ダウンロード時間超過
-50000 InternalServerError サーバーエラー

ディープタギング

Tag

  • 入力画像からファッションアイテムのタグ情報を検出するAPIです。

リクエスト

[URI]

メソッド URI
GET /nhn-ai-fashion/v1.0/appkeys/{appKey}/service/{serviceID}/tag

[Path Variable]

名前 説明
appKey 統合AppkeyまたはサービスAppkey
serviceID サービスID

[URL Parameter]

名前 タイプ 必須 説明
path String O https://imagecdn.co.kr/sample_image.jpg URL Encodeされた画像URL
lang String X ko labelの言語
default: en
en: English
ko: Korean
jp: Japanese
item_limit int X 3 画像で見つかったファッションアイテムのうち、タグ情報を返すアイテムの数
アイテムの幅が長い順にソート
default:1
最大サイズ
1以上4以下に設定可能
リクエスト例
curl -X GET "${domain}/nhn-ai-fashion/v1.0/appkeys/{appKey}/service/{serviceID}/tag?path=https%3A%2F%2Fimagecdn.co.kr%2Fsample_image.jpg&lang=en&item_limit=3"

レスポンス

[レスポンス本文データ]

名前 タイプ 必須 説明
data.totalCount Number O 2 検索結果の総数
data.query String O path=https://imagecdn.co.kr/sample_image.jpg&lang=ko&item_limit=3 検索クエリ
data.items[].type String O JACKET 検出されたアイテムのtype
data.items[].score float32 O 0.9515 検出されたアイテムの信頼度
data.items[].tags Array of json object O 検出されたアイテムタグ情報の配列
data.items[].tags[].attribute String O category タグのプロパティ
data.items[].tags[].labels Array of json object O タグラベルの配列
data.items[].tags[].labels[].label String O ブラウス| Blouse タグラベル
URL Parameterのlangによりレスポンス言語が異なる
data.items[].tags[].labels[].score float32 O 0.9545 タグラベルの信頼度
data.items[].center float64 array O [0.825047801147227, 0.330948979591837] 検出されたアイテムの中央x、y座標%
data.items[].b0 float64 array O [0.676864247418738, 0.219377551020408] 検出されたアイテムのx0、y0座標%
data.items[].b1 float64 array O [0.973231355525813, 0.4426204081632654] 検出されたアイテムのx1、y1座標%


レスポンス本文例

{
    "header": {
        "isSuccessful": true,
        "resultCode": 0,
        "resultMessage": "SUCCESS"
    },
    "data": {
        "totalCount": 2,
        "query": "path=https%3A%2F%2Fimagecdn.co.kr%2Fsample_image.jpg&lang=en&item_limit=3",
        "items": [{
            "type": "SHIRT",
            "tags": [{
                "attribute": "category", "labels": [{ "label": "Blouse", "score": 0.9966272115707397 }]
            }, {
                "attribute": "color", "labels": [{ "label": "Beige", "score": 0.7692235112190247 }]
            }, {
                "attribute": "pattern", "labels": [{ "label": "Solid", "score": 0.9893960356712341 }]
            }, {
                "attribute": "fabric", "labels": [{ "label": "Silk", "score": 0.586938738822937 }]
            }, {
                "attribute": "neckline", "labels": [{ "label": "ShirtCollar", "score": 0.9922573566436768 }]
            }, {
                "attribute": "shoulder", "labels": [{ "label": "PuffShoulder", "score": 0.5369117856025696 }]
            }, {
                "attribute": "sleeve_length", "labels": [{ "label": "LongSleeve", "score": 0.6998409032821655 }]
            }, {
                "attribute": "sleeve_shape", "labels": [{ "label": "Straight", "score": 0.689109206199646 }]
            }, {
                "attribute": "length_up", "labels": [{ "label": "Waist", "score": 0.9575495719909668 }]
            }, {
                "attribute": "age", "labels": [{ "label": "Adult", "score": 0.9985153079032898 }]
            }, {
                "attribute": "gender", "labels": [{ "label": "Female", "score": 0.9960111379623413 }]
            }, {
                "attribute": "detail", "labels": [{ "label": "Buttoned", "score": 0.9440848231315613 }]
            }, {
                "attribute": "fit", "labels": [{ "label": "Normal/Regular", "score": 0.789472222328186 }]
            }],
            "center": [ 0.46125, 0.34125 ],
            "b0": [ 0.1875, 0.0175 ],
            "b1": [ 0.735, 0.665 ],
            "score": 0.93118
        }, {
            "type": "SKIRT",
            "tags": [{
                "attribute": "category", "labels": [{ "label": "Skirt", "score": 0.9997897744178772 }]
            }, {
                "attribute": "color", "labels": [{ "label": "Brown", "score": 0.8597127199172974 }]
            }, {
                "attribute": "pattern", "labels": [{ "label": "Solid", "score": 0.988312304019928 }]
            }, {
                "attribute": "fabric", "labels": [{ "label": "Canvas", "score": 0.24775846302509308 }]
            }, {
                "attribute": "length_lo", "labels": [{ "label": "Short/Thigh", "score": 0.9987099170684814 }]
            }, {
                "attribute": "age", "labels": [{ "label": "Adult", "score": 0.9993846416473389 }]
            }, {
                "attribute": "gender", "labels": [{ "label": "Female", "score": 0.9950520396232605 }]
            }, {
                "attribute": "detail", "labels": [{ "label": "WrapStyle", "score": 0.7058117985725403 }]
            }, {
                "attribute": "fit", "labels": [{ "label": "Normal/Regular", "score": 0.9844645857810974 }]
            }, {
                "attribute": "shape", "labels": [{ "label": "A-line", "score": 0.9432026743888855 }]
            }],
            "center": [ 0.5, 0.69125 ],
            "b0": [ 0.28, 0.445 ],
            "b1": [ 0.72, 0.9375 ],
            "score": 0.939945
        }]
    }
}

エラーコード

resultCode resultMessage 説明
-40000 InvalidParam パラメータにエラーがある
-41000 UnauthorizedAppKey 承認されていないAppkey
-42000 NotExistServiceID 登録されていないサービスID
-45020 ImageTooLargeException 画像ファイルのサイズが大きすぎる
入力画像ガイド参考
-45040 InvalidImageFormatException サポートしない画像ファイル形式
入力画像ガイド参考
-45050 InvalidImageURLException アクセスできないURL
-45060 ImageTimeoutError 画像ダウンロード時間超過
-50000 InternalServerError サーバーエラー
TOP